home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / f90 / omp_threads.z / omp_threads
Encoding:
Text File  |  1998-10-30  |  14.8 KB  |  249 lines
  1. OMP_THREADS(3)                                        Last changed: 2-24-98
  2.  
  3.  
  4. NNAAMMEE
  5.      oommpp__sseett__nnuumm__tthhrreeaaddss, oommpp__ggeett__nnuumm__tthhrreeaaddss, oommpp__ggeett__mmaaxx__tthhrreeaaddss,
  6.      oommpp__ggeett__tthhrreeaadd__nnuumm, oommpp__ggeett__nnuumm__pprrooccss, oommpp__sseett__ddyynnaammiicc,
  7.      oommpp__ggeett))ddyynnaammiicc, oommpp__iinn__ppaarraalllleell, OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS,
  8.      OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS, OOMMPP__GGEETT__MMAAXX__TTHHRREEAADDSS, OOMMPP__GGEETT__TTHHRREEAADD__NNUUMM,
  9.      OOMMPP__GGEETT__NNUUMM__PPRROOCCSS, OOMMPP__SSEETT__DDYYNNAAMMIICC, OOMMPP__GGEETT__DDYYNNAAMMIICC, OOMMPP__IINN__PPAARRAALLLLEELL -
  10.      Runtime library procedures used to set, call or return numbers of
  11.      threads
  12.  
  13. SSYYNNOOPPSSIISS
  14.      C/C++: (Deferred implementation)
  15.           ##iinncclluuddee <<oommpp__sseett__nnuumm__tthhrreeaaddss>>
  16.           vvooiidd oommpp__sseett__nnuumm__tthhrreeaaddss ((_i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n))
  17.  
  18.           ##iinncclluuddee <<oommpp__ggeett__nnuumm__tthhrreeaaddss>>
  19.           iinntt oommpp__ggeett__nnuumm__tthhrreeaaddss(())
  20.  
  21.           ##iinncclluuddee <<oommpp__ggeett__mmaaxx__tthhrreeaaddss>>
  22.           iinntt oommpp__ggeett__mmaaxx__tthhrreeaaddss(())
  23.  
  24.           ##iinncclluuddee <<oommpp__ggeett__tthhrreeaadd__nnuumm>>
  25.           iinntt oommpp__ggeett__tthhrreeaadd__nnuumm(())
  26.  
  27.           ##iinncclluuddee <<oommpp__ggeett__nnuumm__pprrooccss>>
  28.           iinntt oommpp__ggeett__nnuumm__pprrooccss(())
  29.  
  30.           ##iinntteeggeerr <<oommpp__sseett__ddyynnaammiicc>>
  31.           vvooiidd oommpp__sseett__ddyynnaammiicc((_i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n))
  32.  
  33.           ##iinntteeggeerr <<oommpp__ggeett__ddyynnaammiicc>>
  34.           iinntt oommpp__ggeett__ddyynnaammiicc(())
  35.  
  36.           ##iinntteeggeerr <<oommpp__iinn__ppaarraalllleell>>
  37.           vvooiidd oommpp__iinn__ppaarraalllleell(())
  38.  
  39.      Fortran:
  40.           CCAALLLL OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS ((_i_n_t_e_g_e_r-_e_p_x_r_e_s_s_i_o_n))
  41.  
  42.           IINNTTEEGGEERR OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS(())
  43.  
  44.           IINNTTEEGGEERR OOMMPP__GGEETT__MMAAXX__TTHHRREEAADDSS(())
  45.  
  46.           IINNTTEEGGEERR OOMMPP__GGEETT__TTHHRREEAADD__NNUUMM(())
  47.  
  48.           IINNTTEEGGEERR OOMMPP__GGEETT__NNUUMM__PPRROOCCSS(())
  49.  
  50.           CCAALLLL OOMMPP__SSEETT__DDYYNNAAMMIICC((_l_o_g_i_c_a_l-_e_x_p_r_e_s_s_i_o_n))
  51.  
  52.           LLOOGGIICCAALL OOMMPP__GGEETT__DDYYNNAAMMIICC(())
  53.  
  54.           LLOOGGIICCAALL OOMMPP__IINN__PPAARRAALLLLEELL(())
  55.  
  56. IIMMPPLLEEMMEENNTTAATTIIOONN
  57.      IRIX systems
  58.  
  59. SSTTAANNDDAARRDDSS
  60.      OpenMP Fortran API
  61.  
  62. DDEESSCCRRIIPPTTIIOONN
  63.      The following descriptions contain information for Fortran and C/C++.
  64.  
  65.      oommpp__sseett__nnuumm__tthhrreeaaddss, OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS
  66.           This procedure sets the number of threads to use in a team.
  67.  
  68.      The _i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n is evaluated, and its value is used as the
  69.      number of threads to use beginning with the next non-nested parallel
  70.      region.
  71.  
  72.      This call takes precedence over the OOMMPP__NNUUMM__TTHHRREEAADDSS environment
  73.      varable.  When dynamic threads is enabled, this value is interpreted
  74.      to be the maximum number of threads to use.
  75.  
  76.      oommpp__ggeett__nnuumm__tthhrreeaaddss, OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS
  77.           This function returns the number of threads currently in the team
  78.           executing the parallel region from which it is called.
  79.           Mechanisms that control the number of threads include the runtime
  80.           system when dynamic adjustment of the number of threads is
  81.           enabled, the oommpp__sseett__nnuumm__tthhrreeaaddss(()) call (OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS
  82.           call), and the OOMMPP__NNUUMM__TTHHRREEAADDSS environment variable.  The default
  83.           number of threads is implementation dependent in the case that
  84.           the number of threads has not been specified by the user.
  85.  
  86.           This function binds to the closest enclosing ppaarraalllleell (PPAARRAALLLLEELL)
  87.           directive.  When called from a nested parallel region that is
  88.           serialized, this function returns 1.
  89.  
  90.      oommpp__ggeett__mmaaxx__tthhrreeaaddss, OOMMPP__GGEETT__MMAAXX__TTHHRREEAADDSS
  91.           This function returns the maximum value that calls to
  92.           oommpp__ggeett__nnuumm__tthhrreeaaddss (OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS) may return.  If
  93.           oommpp__sseett__nnuumm__tthhrreeaaddss (OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS) is called with a larger
  94.           value, subsequent calls o this function will return the larger
  95.           value.  This function may be used to allocate maximal sized per-
  96.           thread data structures when oommpp__sseett__ddyynnaammiicc (OOMMPP__SSEETT__DDYYNNAAMMIICC) is
  97.           set to nnoonn--zzeerroo (TTRRUUEE).  This function has global scope and
  98.           returns the maximum value whether executing from a serial region
  99.           or a parallel region.
  100.  
  101.      oommpp__ggeett__tthhrreeaadd__nnuumm, OOMMPP__GGEETT__TTHHRREEAADD__NNUUMM
  102.           This function returns the thread number within the team.  The
  103.           master thread of the team is thread 0.  The thread number is
  104.           between 0 and oommpp__ggeett__nnuumm__tthhrreeaaddss(())-1 (OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS(())-1)
  105.           inclusive.  This function binds to the closest enclosing ppaarraalllleell
  106.           (PPAARRAALLLLEELL) directive.  If called from a serial region, it returns
  107.           0.  If called from within a nested parallel region that is
  108.           serialized, this function returns 0.
  109.  
  110.      oommpp__ggeett__nnuumm__pprrooccss, OOMMPP__GGEETT__NNUUMM__PPRROOCCSS
  111.           This function returns the number of processors that are available
  112.           to the program.
  113.  
  114.      oommpp__sseett__ddyynnaammiicc, OOMMPP__SSEETT__DDYYNNAAMMIICC
  115.           This function enables or disables dynamic adjustment of the
  116.           number of threads available for execution of parallel regions.
  117.  
  118.           If _i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n (_l_o_g_i_c_a_l-_e_x_p_r_e_s_s_i_o_n) _e_v_a_l_u_a_t_e_s _t_o nnoonn--zzeerroo
  119.           (TTRRUUEE), the number of threads that are used for executing
  120.           subsequent parallel regions may be adjusted automatically by the
  121.           runtime environment to best utilize system resources.  As a
  122.           consequece, the number of threads specified by the user may
  123.           actually be interpreted as a maximum thread count.  The number of
  124.           threads always remains fixed over the duration of each parallel
  125.           region and is reported by oommpp__ggeett__nnuumm__tthhrreeaaddss(())
  126.           (OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS).  If _i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n (_l_o_g_i_c_a_l-
  127.           _e_x_p_r_e_s_s_i_o_n) evaluates to zzeerroo (FFAALLSSEE), dynamic adjustment is
  128.           disabled.
  129.  
  130.           A call to oommpp__sseett__ddyynnaammiicc (OOMMPP__SSEETT__DDYYNNAAMMIICC) has precedence over
  131.           the OOMMPP__DDYYNNAAMMIICC environment variable.  The default for the
  132.           dynamic adjustment of threads is implementation dependent.  As a
  133.           result, user codes that depend on a specific number of threads
  134.           for correct execution should explicitly disable dynamic threads.
  135.           Implementations are not required to provide the ability to
  136.           dynamically adjust the number of threads, but they are required
  137.           to provide the interface to support portability across all
  138.           platforms.
  139.  
  140.      oommpp__ggeett__ddyynnaammiicc, OOMMPP__GGEETT__DDYYNNAAMMIICC
  141.           This function returns nnoonn--zzeerroo (TTRRUUEE) if dynamic adjustment of
  142.           the number of threads is enabled; otherwise, it returns zzeerroo
  143.           (FFAALLSSEE).
  144.  
  145.      oommpp__iinn__ppaarraalllleell, OOMMPP__IINN__PPAARRAALLLLEELL
  146.           This function returns nnoonn--zzeerroo (TTRRUUEE) if it is within the dynamic
  147.           extent of a parallel region that actually went parallel;
  148.           otherwise, it returns zzeerroo (FFAALLSSEE).  This function can be used to
  149.           determine whether it was called from within a parallel region.
  150.           It has global scope and will return TTRRUUEE from within a nested
  151.           parallel region.
  152.  
  153. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
  154.      OOMMPP__SSCCHHEEDDUULLEE
  155.           This variable applies only to DDOO and PPAARRAALLLLEELL DDOO directives that
  156.           have the schedule type RRUUNNTTIIMMEE.  The schedule type and chunk size
  157.           for all such loops can be set at runtime by setting this
  158.           environment variable to any of the recognized schedule types and
  159.           to an optional chunk size.  For DDOO and PPAARRAALLLLEELL DDOO directives
  160.           that have a schedule type other than RRUUNNTTIIMMEE, this environment
  161.           variable is ignored.  The default value for this environment
  162.           variable is implementation dependent.  If the optional chunk size
  163.           is not set, a chunk size of 1 is assumed, except in the case of a
  164.           SSTTAATTIICC schedule, the chunk size is set to the loop iteration
  165.           space divided by the number of threads applied to the loop.
  166.  
  167.      OOMMPP__NNUUMM__TTHHRREEAADDSS
  168.           This variable sets the number of threads to use during execution,
  169.           unless that number is explicitly changed by calling
  170.           oommpp__sseett__nnuumm__tthhrreeaaddss(()).  When dynamic adjustment of the number of
  171.           threads is enalbed, the value of this environment variable may be
  172.           interpreted as the maximum number of threads to use.  The default
  173.           value is implementation dependent.
  174.  
  175.      OOMMPP__DDYYNNAAMMIICC
  176.           This variable enables or disables dynamic adjustment of the
  177.           number of threads available for execution of parallel regions.
  178.           If set to TTRRUUEE, the number of threads that are used for executing
  179.           parallel regions may be adjusted by the runtime environment to
  180.           best utilize system resources.
  181.  
  182.           If set to FFAALLSSEE, dynamic adjustment is disabled.  The default
  183.           condition is implementation dependent.
  184.  
  185.      OOMMPP__NNEESSTTEEDD
  186.           This variable enables or disables nested parallelism.  If set to
  187.           TTRRUUEE, nested parallelism is enabled; if it is set to FFAALLSSEE, it is
  188.           disabled.  The default value is FFAALLSSEE.
  189.  
  190. EEXXAAMMPPLLEESS
  191.      Example 1.
  192.  
  193.      rreevviieewweerrss -- tthhee ffoolllloowwiinngg ppaarraaggrraapphh ccoonnttaaiinnss ssoommee ""iimmpplleemmeennttaattiioonn--
  194.      ddeeppeennddeenntt"" wwoorrddiinngg ffrroomm tthhee OOppeennMMPP ssttaannddaarrdd..  hhooww sshhoouulldd tthhiiss
  195.      ppaarraaggrraapphh bbee mmooddiiffiieedd ffoorr SSGGII//CCrraayy''ss iimmpplleemmeennttaattiioonn ooff OOppeennMMPP??
  196.  
  197.      Some programs rely on a fixed, prespecified number of threads to
  198.      execute correctly.  Because the default setting for the dynamic
  199.      adjustment of the number of threads is implementation-dependent, such
  200.      programs can choose to turn off the dynamic threads capability and set
  201.      the number of threads explicitly.  This ensures portability.  The
  202.      following Fortran 90 code fragment specifies a fixed number of
  203.      threads:
  204.  
  205.                 CALL OMP_SET_DYNAMIC(.FALSE.)
  206.                 CALL OMP_SET_NUM_THREADS(16)
  207.           !$OMP PARALLEL DEFAULT(PRIVATE)SHARED(X,NPOINTS)
  208.                 IAM = OMP_GET_THREAD_NUM()
  209.                 IPOINTS = NPOINTS/16
  210.                 CALL DO_BY_16(X,IAM,IPOINTS)
  211.           !$OMP END PARALLEL
  212.  
  213.      In the preceding code fragment, the code executes correctly only if it
  214.      is executed by 16 threads.  Note that the number of threads executing
  215.      a parallel region remains constant during a parallel region,
  216.      regardless of the dynamic threads setting.  The dynamic threads
  217.      mechanism determines the number of threads to use at the start of the
  218.      parallel region and keeps it constant for the duration of the region.
  219.  
  220.      Example 2.  Consider the following incorrect Fortran 90 code:
  221.  
  222.                 NP = OMP_GET_NUM_THREADS()
  223.           !$OMP PARALLEL DO SCHEDULE(STATIC)
  224.                 DO I = 0, NP-1
  225.                   CALL WORK(I)
  226.                 ENDDO
  227.           !$OMP END PARALLEL DO
  228.  
  229.      The OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS(()) call returns 1 in the serial section of the
  230.      code, so NNPP will always be equal to 1.
  231.  
  232.      To determine the number of threads that will be deployed for the
  233.      parallel region, the call should be inside the parallel region.  The
  234.      following code is a rewrite of the preceding code.  It shows how to
  235.      rewrite the program without including a query for the number of
  236.      threads:
  237.  
  238.           !$OMP PARALLEL PRIVATE(I)
  239.                 I = OMP_GET_THREAD_NUM()
  240.                 CALL WORK(I)
  241.           !$OMP END PARALLEL
  242.  
  243. SSEEEE AALLSSOO
  244.      oommpp__lloocckk(3) for information on how to manipulate locks
  245.  
  246.      oommpp__nneesstteedd(3) to manipulate or report status of nested parallelism
  247.  
  248.      This man page is available only online.
  249.